/*
 * Copyright (C) 2023 Huawei Device Co., Ltd.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * @addtogroup VideoDecoder
 * @{
 *
 * @brief The VideoDecoder module provides interfaces for video decoding.
 *
 * @syscap SystemCapability.Multimedia.Media.VideoDecoder
 * @since 9
 * @version 1.0
 */

/**
 * @file native_avcodec_videodecoder.h
 *
 * @brief Declare the Native API used for video decoding.
 *
 * @kit AVCodecKit
 * @library libnative_media_vdec.so
 * @syscap SystemCapability.Multimedia.Media.VideoDecoder
 * @since 9
 */

#ifndef NATIVE_AVCODEC_VIDEODECODER_H
#define NATIVE_AVCODEC_VIDEODECODER_H

#include <stdint.h>
#include <stdio.h>
#include "native_avcodec_base.h"

#ifdef __cplusplus
extern "C" {
#endif

typedef struct MediaKeySession MediaKeySession;

/**
 * @brief Creates a video decoder instance from the mime type, it is recommended to use.
 * @syscap SystemCapability.Multimedia.Media.VideoDecoder
 * @param mime mime type description string, refer to {@link AVCODEC_MIME_TYPE}
 * @return Returns a Pointer to an OH_AVCodec instance.
 * Return NULL if memory ran out or the mime type is not supported.
 * @since 9
 * @version 1.0
 */
OH_AVCodec *OH_VideoDecoder_CreateByMime(const char *mime);

/**
 * @brief Create a video decoder instance through the video decoder name.
 * The premise of using this interface is to know the exact name of the decoder.
 * The decoder name can be obtained through capability query.
 * @syscap SystemCapability.Multimedia.Media.VideoDecoder
 * @param name video codec name
 * @return Returns a Pointer to an OH_AVCodec instance.
 * Return NULL if memory ran out or the decoder name is not supported.
 * @since 9
 * @version 1.0
 */
OH_AVCodec *OH_VideoDecoder_CreateByName(const char *name);

/**
 * @brief Clear the internal resources of the decoder and destroy the decoder instance.
 * Can not be destroyed repeatedly.
 * @syscap SystemCapability.Multimedia.Media.VideoDecoder
 * @param codec Pointer to an OH_AVCodec instance
 * @return Returns AV_ERR_OK if succeed,
 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}.
 * {@link AV_ERR_NO_MEMORY}, instance has already destroyed.
 * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non decoder instance or NULL.
 * {@link AV_ERR_UNKNOWN}, unknown error.
 * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error.
 * @since 9
 * @version 1.0
 */
OH_AVErrCode OH_VideoDecoder_Destroy(OH_AVCodec *codec);

/**
 * @brief Set the asynchronous callback function so that your application can respond to the events
 * generated by the video decoder. This interface must be called before Prepare is called.
 * @syscap SystemCapability.Multimedia.Media.VideoDecoder
 * @param codec Pointer to an OH_AVCodec instance
 * @param callback A collection of all callback functions, see {@link OH_AVCodecAsyncCallback}
 * @param userData The data that the user rely on to execute the callback
 * @return Returns AV_ERR_OK if the execution is successful,
 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}.
 * {@link AV_ERR_NO_MEMORY}, instance has already destroyed.
 * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non decoder instance or NULL.
 * {@link AV_ERR_UNKNOWN}, unknown error.
 * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error.
 * @deprecated since 11
 * @useinstead OH_VideoDecoder_RegisterCallback
 * @since 9
 * @version 1.0
 */
OH_AVErrCode OH_VideoDecoder_SetCallback(OH_AVCodec *codec, OH_AVCodecAsyncCallback callback, void *userData);

/**
 * @brief Set the asynchronous callback function so that your application can respond to the events
 * generated by the video decoder. This interface must be called before Prepare is called.
 * @syscap SystemCapability.Multimedia.Media.VideoDecoder
 * @param codec Pointer to an OH_AVCodec instance
 * @param callback A collection of all callback functions, see {@link OH_AVCodecCallback}
 * @param userData The data that the user rely on to execute the callback
 * @return Returns AV_ERR_OK if the execution is successful,
 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}.
 * {@link AV_ERR_NO_MEMORY}, instance has already destroyed.
 * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non decoder instance or NULL.
 * {@link AV_ERR_UNKNOWN}, unknown error.
 * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error.
 * @since 11
 */
OH_AVErrCode OH_VideoDecoder_RegisterCallback(OH_AVCodec *codec, OH_AVCodecCallback callback, void *userData);

/**
 * @brief Specify the output surface to provide video decoding output,
 * this interface must be called before Prepare is called.
 * This interface can be directly called in the Executing state.
 * @syscap SystemCapability.Multimedia.Media.VideoDecoder
 * @param codec Pointer to an OH_AVCodec instance
 * @param window A pointer to a OHNativeWindow instance, see {@link OHNativeWindow}
 * @return Returns AV_ERR_OK if the execution is successful,
 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}.
 * {@link AV_ERR_NO_MEMORY}, instance has already destroyed.
 * {@link AV_ERR_OPERATE_NOT_PERMIT}, not permit to call the interface in Buffer mode.
 * {@link AV_ERR_INVALID_VAL}
 * 1. the input codec pointer is non decoder instance or NULL;
 * 2. window is NULL.
 * {@link AV_ERR_UNKNOWN}, unknown error.
 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state.
 * @since 9
 * @version 1.0
 */
OH_AVErrCode OH_VideoDecoder_SetSurface(OH_AVCodec *codec, OHNativeWindow *window);

/**
 * @brief To configure the video decoder, typically, you need to configure the description information of the decoded
 * video, which can be extracted from the OH_AVSource. This interface must be called before Prepare is called.
 * @syscap SystemCapability.Multimedia.Media.VideoDecoder
 * @param codec Pointer to an OH_AVCodec instance
 * @param format A pointer to an OH_AVFormat to give the description of the video track to be decoded
 * @return Returns AV_ERR_OK if the execution is successful,
 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}.
 * {@link AV_ERR_NO_MEMORY}, instance has already destroyed.
 * {@link AV_ERR_INVALID_VAL}
 * 1. the input codec pointer is non decoder instance or NULL;
 * 2. Invalid param in format.
 * {@link AV_ERR_UNKNOWN}, unknown error.
 * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error.
 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state, must be called before Prepare.
 * {@link AV_ERR_VIDEO_UNSUPPORTED_COLOR_SPACE_CONVERSION}, video unsupported color space conversion.
 * @since 9
 * @version 1.0
 */
OH_AVErrCode OH_VideoDecoder_Configure(OH_AVCodec *codec, OH_AVFormat *format);

/**
 * @brief Prepare the internal resources of the decoder, the Configure interface must be called before
 * calling this interface.
 * @syscap SystemCapability.Multimedia.Media.VideoDecoder
 * @param codec Pointer to an OH_AVCodec instance
 * @return Returns AV_ERR_OK if the execution is successful,
 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}.
 * {@link AV_ERR_NO_MEMORY}, instance has already destroyed.
 * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non decoder instance or NULL.
 * {@link AV_ERR_UNKNOWN}, unknown error.
 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state.
 * {@link AV_ERR_OPERATE_NOT_PERMIT}
 * 1. internal execution error；
 * 2. decoder is in Buffer mode and color space conversion is configured.
 * @since 9
 * @version 1.0
 */
OH_AVErrCode OH_VideoDecoder_Prepare(OH_AVCodec *codec);

/**
 * @brief Start the decoder, this interface must be called after the Prepare is successful.
 * After being successfully started, the decoder will start reporting NeedInputData events.
 * @syscap SystemCapability.Multimedia.Media.VideoDecoder
 * @param codec Pointer to an OH_AVCodec instance
 * @return Returns AV_ERR_OK if the execution is successful,
 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}.
 * {@link AV_ERR_NO_MEMORY}, instance has already destroyed.
 * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non decoder instance or NULL.
 * {@link AV_ERR_UNKNOWN}, unknown error.
 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state.
 * {@link AV_ERR_OPERATE_NOT_PERMIT}
 * 1. internal execution error;
 * 2. video color space conversion is configured but decoder is not Prepared.
 * @since 9
 * @version 1.0
 */
OH_AVErrCode OH_VideoDecoder_Start(OH_AVCodec *codec);

/**
 * @brief Stop the decoder and release the input and output buffer. After stopping,
 * you can re-enter the Running state through Start, but it should be noted that
 * if Codec-Specific-Data has been input to the decoder before, it needs to be input again.
 * @syscap SystemCapability.Multimedia.Media.VideoDecoder
 * @param codec Pointer to an OH_AVCodec instance
 * @return Returns AV_ERR_OK if the execution is successful,
 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}.
 * {@link AV_ERR_NO_MEMORY}, instance has already destroyed.
 * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non decoder instance or NULL.
 * {@link AV_ERR_UNKNOWN}, unknown error.
 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state.
 * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error.
 * @since 9
 * @version 1.0
 */
OH_AVErrCode OH_VideoDecoder_Stop(OH_AVCodec *codec);

/**
 * @brief Clear the input and output data buffered and parameters in the decoder, for example, PPS/SPS in H264 format.
 * After this interface is called, all the buffer indexes previously reported through the asynchronous callback
 * will be invalidated, make sure not to access the buffers corresponding to these indexes.
 * @syscap SystemCapability.Multimedia.Media.VideoDecoder
 * @param codec Pointer to an OH_AVCodec instance
 * @return Returns AV_ERR_OK if the execution is successful,
 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}.
 * {@link AV_ERR_NO_MEMORY}, instance has already destroyed.
 * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non decoder instance or NULL.
 * {@link AV_ERR_UNKNOWN}, unknown error.
 * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error.
 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state.
 * @since 9
 * @version 1.0
 */
OH_AVErrCode OH_VideoDecoder_Flush(OH_AVCodec *codec);

/**
 * @brief Reset the decoder, the decoder returns to the Initialized state.
 * To continue decoding, you need to call the Configure interface again to configure the decoder instance.
 * @syscap SystemCapability.Multimedia.Media.VideoDecoder
 * @param codec Pointer to an OH_AVCodec instance
 * @return Returns AV_ERR_OK if the execution is successful,
 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}.
 * {@link AV_ERR_NO_MEMORY}, instance has already destroyed.
 * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non decoder instance or NULL.
 * {@link AV_ERR_UNKNOWN}, unknown error.
 * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error.
 * @since 9
 * @version 1.0
 */
OH_AVErrCode OH_VideoDecoder_Reset(OH_AVCodec *codec);

/**
 * @brief Get the description information of the output data of the decoder, refer to {@link OH_AVFormat}
 * It should be noted that the life cycle of the OH_AVFormat instance pointed to by the return value * needs
 * to be released by {@link OH_AVFormat_Destroy}.
 * @syscap SystemCapability.Multimedia.Media.VideoDecoder
 * @param codec Pointer to an OH_AVCodec instance
 * @return Returns a pointer to an OH_AVFormat instance.
 * Return NULL if the decoder is NULL or invalid.
 * @since 9
 * @version 1.0
 */
OH_AVFormat *OH_VideoDecoder_GetOutputDescription(OH_AVCodec *codec);

/**
 * @brief Set dynamic parameters to the decoder. Note: This interface can only be called after the decoder is started.
 * At the same time, incorrect parameter settings may cause decoding failure.
 * @syscap SystemCapability.Multimedia.Media.VideoDecoder
 * @param codec Pointer to an OH_AVCodec instance
 * @param format pointer to an OH_AVFormat instance
 * @return Returns AV_ERR_OK if the execution is successful,
 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}.
 * {@link AV_ERR_NO_MEMORY}, instance has already destroyed.
 * {@link AV_ERR_INVALID_VAL}
 * 1. the input codec pointer is non decoder instance or NULL;
 * 2. invalid param in format.
 * {@link AV_ERR_UNKNOWN}, unknown error.
 * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error.
 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state.
 * @since 9
 * @version 1.0
 */
OH_AVErrCode OH_VideoDecoder_SetParameter(OH_AVCodec *codec, OH_AVFormat *format);

/**
 * @brief Submit the input buffer filled with data to the video decoder. The {@link OH_AVCodecOnNeedInputData} callback
 * will report the available input buffer and the corresponding index value. Once the buffer with the specified index
 * is submitted to the video decoder, the buffer cannot be accessed again until the {@link OH_AVCodecOnNeedInputData}
 * callback is received again reporting that the buffer with the same index is available. In addition, for some
 * decoders, it is required to input Codec-Specific-Data to the decoder at the beginning to initialize the decoding
 * process of the decoder, such as PPS/SPS data in H264 format.
 * @syscap SystemCapability.Multimedia.Media.VideoDecoder
 * @param codec Pointer to an OH_AVCodec instance
 * @param index Enter the index value corresponding to the buffer, should be given by {@link OH_AVCodecOnNeedInputData}.
 * @param attr Information describing the data contained in the buffer
 * @return Returns AV_ERR_OK if the execution is successful,
 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}.
 * {@link AV_ERR_NO_MEMORY}, instance has already destroyed.
 * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non decoder instance or NULL.
 * {@link AV_ERR_UNKNOWN}, unknown error.
 * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error.
 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state.
 * @deprecated since 11
 * @useinstead OH_VideoDecoder_PushInputBuffer
 * @since 9
 * @version 1.0
 */
OH_AVErrCode OH_VideoDecoder_PushInputData(OH_AVCodec *codec, uint32_t index, OH_AVCodecBufferAttr attr);

/**
 * @brief Return the processed output buffer to the decoder, and notify the decoder to finish rendering the
 * decoded data contained in the buffer on the output surface. If the output surface is not configured before,
 * calling this interface only returns the output buffer corresponding to the specified index to the decoder.
 * @syscap SystemCapability.Multimedia.Media.VideoDecoder
 * @param codec Pointer to an OH_AVCodec instance
 * @param index The index value corresponding to the output buffer, should be given by {@link OH_AVCodecOnNewOutputData}
 * @return Returns AV_ERR_OK if the execution is successful,
 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}.
 * {@link AV_ERR_NO_MEMORY}, instance has already destroyed.
 * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non decoder instance or NULL.
 * {@link AV_ERR_UNKNOWN}, unknown error.
 * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error.
 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state.
 * @deprecated since 11
 * @useinstead OH_VideoDecoder_RenderOutputBuffer
 * @since 9
 * @version 1.0
 */
OH_AVErrCode OH_VideoDecoder_RenderOutputData(OH_AVCodec *codec, uint32_t index);

/**
 * @brief Return the processed output buffer to the decoder.
 * @syscap SystemCapability.Multimedia.Media.VideoDecoder
 * @param codec Pointer to an OH_AVCodec instance
 * @param index The index value corresponding to the output buffer,
 * should be given by {@link OH_AVCodecOnNewOutputData}.
 * @return Returns AV_ERR_OK if the execution is successful,
 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}.
 * {@link AV_ERR_NO_MEMORY}, instance has already destroyed.
 * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non decoder instance or NULL.
 * {@link AV_ERR_UNKNOWN}, unknown error.
 * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error.
 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state.
 * @deprecated since 11
 * @useinstead OH_VideoDecoder_FreeOutputBuffer
 * @since 9
 * @version 1.0
 */
OH_AVErrCode OH_VideoDecoder_FreeOutputData(OH_AVCodec *codec, uint32_t index);

/**
 * @brief Notify the video decoder that the buffer corresponding to the index has been filled with input data.
 * {@link OH_AVCodecOnNeedInputBuffer} callback will report the available input buffer and
 * the corresponding index value. Once the buffer with the specified index is submitted to the video decoder,
 * the buffer cannot be accessed again until the {@link OH_AVCodecOnNeedInputBuffer} callback is received again
 * reporting that the buffer with the same index is available. In addition, for some decoders, it is required
 * to input Codec-Specific-Data to the decoder at the beginning to initialize the decoding process of the decoder,
 * such as PPS/SPS data in H264 format. The invoker can use this interface to transfer the parameters required
 * for decoding to the decoder, such as PPS/SPS data in H264 format.
 * The parameters can be sent to the decoder independently or together with the data to be decoded.
 * @syscap SystemCapability.Multimedia.Media.VideoDecoder
 * @param codec Pointer to an OH_AVCodec instance
 * @param index The index of the input buffer, should be given by {@link OH_AVCodecOnNeedInputBuffer}.
 * @return Returns AV_ERR_OK if the execution is successful,
 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}.
 * {@link AV_ERR_NO_MEMORY}, instance has already destroyed.
 * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non decoder instance or NULL.
 * {@link AV_ERR_UNKNOWN}, unknown error.
 * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error.
 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state.
 * @since 11
 */
OH_AVErrCode OH_VideoDecoder_PushInputBuffer(OH_AVCodec *codec, uint32_t index);

/**
 * @brief Return the processed output buffer to the decoder, and notify the decoder to finish rendering the
 * decoded data contained in the buffer on the output surface. If the output surface is not configured before,
 * calling this interface only returns the output buffer corresponding to the specified index to the decoder.
 * @syscap SystemCapability.Multimedia.Media.VideoDecoder
 * @param codec Pointer to an OH_AVCodec instance
 * @param index The index value corresponding to the output buffer,
 * should be given by {@link OH_AVCodecOnNewOutputBuffer}.
 * @return Returns AV_ERR_OK if the execution is successful,
 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}.
 * {@link AV_ERR_NO_MEMORY}, instance has already destroyed.
 * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non decoder instance or NULL.
 * {@link AV_ERR_UNKNOWN}, unknown error.
 * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error.
 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state.
 * @since 11
 */
OH_AVErrCode OH_VideoDecoder_RenderOutputBuffer(OH_AVCodec *codec, uint32_t index);

/**
 * @brief Return the processed output buffer with render timestamp to the decoder, and notify the decoder to finish
 * rendering the decoded data contained in the buffer on the output surface. If the output surface is not configured
 * before, calling this interface only returns the output buffer corresponding to the specified index to the decoder.
 * The timestamp may have special meaning depending on the destination surface.
 * Invoker can use the timestamp to render the buffer at a specific time (at the VSYNC at or after the buffer
 * timestamp). For this to work, the timestamp needs to be reasonably close to the current SystemNanoTime. A few notes:
 * 1. The buffer will not be returned to the codec until the timestamp has passed and the buffer is no longer used by
 *    the surface.
 * 2. buffers are processed sequentially, so you may block subsequent buffers to be displayed on the surface.
 *    This is important if you want to react to user action, e.g. stop the video or seek.
 * 3. If multiple buffers are sent to the surface to be rendered at the same VSYNC, the last one will be shown, and the
 *    other ones will be dropped.
 * 4. If the timestamp is not "reasonably close" to the current system time, the surface will
 *    ignore the timestamp, and display the buffer at the earliest feasible time. In this mode it will not drop frames.
 * @syscap SystemCapability.Multimedia.Media.VideoDecoder
 * @param codec Pointer to an OH_AVCodec instance
 * @param index The index value corresponding to the output buffer, should be given by {@link
 * OH_AVCodecOnNewOutputBuffer}
 * @param renderTimestampNs The timestamp is associated with the output buffer when it is sent to the surface. The unit
 * is nanosecond
 * @return Returns AV_ERR_OK if the execution is successful,
 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}.
 * {@link AV_ERR_NO_MEMORY}, instance has already destroyed.
 * {@link AV_ERR_INVALID_VAL}, the parameter is invalid.
 * {@link AV_ERR_UNKNOWN}, unknown error.
 * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error.
 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state.
 * @since 12
 */
OH_AVErrCode OH_VideoDecoder_RenderOutputBufferAtTime(OH_AVCodec *codec, uint32_t index, int64_t renderTimestampNs);

/**
 * @brief Return the processed output buffer to the decoder.
 * Need to call this interface to release output buffer immediately after using.
 * Otherwise, the decoding process will be blocked.
 * @syscap SystemCapability.Multimedia.Media.VideoDecoder
 * @param codec Pointer to an OH_AVCodec instance
 * @param index The index value corresponding to the output buffer,
 * should be given by {@link OH_AVCodecOnNewOutputBuffer}.
 * @return Returns AV_ERR_OK if the execution is successful,
 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}.
 * {@link AV_ERR_NO_MEMORY}, instance has already destroyed.
 * {@link AV_ERR_INVALID_VAL}
 * 1. the input codec pointer is non decoder instance or NULL;
 * 2. the index is vaild or consecutively assigned to the same index,
 * the error do not affect the subsequent decode process.
 * {@link AV_ERR_UNKNOWN}, unknown error.
 * {@link AV_ERR_OPERATE_NOT_PERMIT}, internal execution error.
 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state.
 * @since 11
 */
OH_AVErrCode OH_VideoDecoder_FreeOutputBuffer(OH_AVCodec *codec, uint32_t index);

/**
 * @brief Queries the index of the next available input buffer.
 *
 * This API must be followed by calling {@link OH_VideoDecoder_GetInputBuffer} to obtain the buffer handle,
 * which should then be passed to the decoder via {@link OH_VideoDecoder_PushInputBuffer}.\n
 * Note: This operation is only supported in synchronous mode.\n
 *
 * @syscap SystemCapability.Multimedia.Media.VideoDecoder
 * @param codec Pointer to an OH_AVCodec instance.
 * @param index The index of the input buffer.
 * @param timeoutUs Timeout duration in microseconds, negative value indicates infinite wait.
 * @return Returns AV_ERR_OK if the execution is successful,
 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}.
 * {@link AV_ERR_NO_MEMORY}, internal errors in the input decode instance, such as an abnormal NULL.
 * {@link AV_ERR_INVALID_VAL}, the decoder is nullptr or invalid.
 * {@link AV_ERR_UNKNOWN}, unknown error.
 * {@link AV_ERR_SERVICE_DIED}, avcodec service is died.
 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state.

 * {@link AV_ERR_OPERATE_NOT_PERMIT}, not permitted in asynchronous mode.
 * {@link AV_ERR_TRY_AGAIN_LATER}, query failed, recommended retry after delay.
 * @since 20
 */
OH_AVErrCode OH_VideoDecoder_QueryInputBuffer(struct OH_AVCodec *codec, uint32_t *index, int64_t timeoutUs);

/**
 * @brief Acquires the handle of an available input buffer.
 *
 * Note: It's only applicable in synchronous mode.\n
 *
 * @syscap SystemCapability.Multimedia.Media.VideoDecoder
 * @param codec Pointer to an OH_AVCodec instance
 * @param index Buffer index obtained via {@link OH_VideoDecoder_QueryInputBuffer}.
 * @return Returns a Pointer to an OH_AVBuffer instance.
 * Return nullptr if no buffer available.
 * @since 20
 */
OH_AVBuffer *OH_VideoDecoder_GetInputBuffer(struct OH_AVCodec *codec, uint32_t index);

/**
 * @brief Queries the index of the next available output buffer.
 *
 * The obtained buffer handle through {@link OH_VideoDecoder_GetOutputBuffer} must be:
 *          - Return to the decoder via {@link OH_VideoDecoder_FreeOutputBuffer}, or
 *          - Rendered using {@link OH_VideoDecoder_RenderOutputBuffer}, or
 *          - Scheduled for rendering with {@link OH_VideoDecoder_RenderOutputBufferAtTime}\n
 * Note: This operation is only supported in synchronous mode.\n
 *
 * @syscap SystemCapability.Multimedia.Media.VideoDecoder
 * @param codec Pointer to an OH_AVCodec instance
 * @param index The index of the output buffer
 * @param timeoutUs Timeout duration in microseconds, negative value indicates infinite wait.
 * @return Returns AV_ERR_OK if the execution is successful,
 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}.
 * {@link AV_ERR_NO_MEMORY}, internal errors in the input decode instance, such as an abnormal NULL.
 * {@link AV_ERR_INVALID_VAL}, the decoder is nullptr or invalid.
 * {@link AV_ERR_UNKNOWN}, unknown error.
 * {@link AV_ERR_SERVICE_DIED}, avcodec service is died.
 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state.
 * {@link AV_ERR_OPERATE_NOT_PERMIT}, not permitted in asynchronous mode.
 * {@link AV_ERR_STREAM_CHANGED}, stream format changed, call {@link OH_VideoDecoder_GetOutputDescription} to
 * retrieve new stream information.
 * {@link AV_ERR_TRY_AGAIN_LATER}, query failed, recommended retry after delay.
 * @since 20
 */
OH_AVErrCode OH_VideoDecoder_QueryOutputBuffer(struct OH_AVCodec *codec, uint32_t *index, int64_t timeoutUs);

/**
 * @brief Acquires the handle of an available output buffer.
 *
 * Note: It's only applicable in synchronous mode.\n
 *
 * @syscap SystemCapability.Multimedia.Media.VideoDecoder
 * @param codec Pointer to an OH_AVCodec instance
 * @param index Buffer index obtained via {@link OH_VideoDecoder_QueryOutputBuffer}.
 * @return Returns a Pointer to an OH_AVBuffer instance.
 * Return nullptr if no buffer available.
 * @since 20
 */
OH_AVBuffer *OH_VideoDecoder_GetOutputBuffer(struct OH_AVCodec *codec, uint32_t index);

/**
 * @brief Check whether the current codec instance is valid. It can be used fault recovery or app
 * switchback from the background.
 * @syscap SystemCapability.Multimedia.Media.VideoDecoder
 * @param codec Pointer to an OH_AVCodec instance
 * @param isValid Output parameter. A pointer to a bool instance, it is true if the codec instance is valid,
 * false if the codec instance is invalid. It is recommend that the invoker initialize isValid to false
 * @return Returns AV_ERR_OK if the execution is successful,
 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}.
 * {@link AV_ERR_INVALID_VAL}, the input codec pointer is non decoder instance or NULL.
 * @since 10
 */
OH_AVErrCode OH_VideoDecoder_IsValid(OH_AVCodec *codec, bool *isValid);

/**
 * @brief Set decryption configuration. Call this interface before calling the Prepare interface.
 *
 * @syscap SystemCapability.Multimedia.Media.VideoDecoder
 * @param codec Pointer to an OH_AVCodec instance
 * @param mediaKeySession A media key session instance with decryption function.
 * @param secureVideoPath Secure video Path. Set the secure video path as true and the non secure video path as false.
 * In Surface mode, both secure and non secure video Path are supported.
 * In Buffer mode, only non secure video Path are supported.
 * @return {@link AV_ERR_OK}, execution is successful
 *         {@link AV_ERR_OPERATE_NOT_PERMIT}
 *         1. internal execution error;
 *         2. the decode service process is abnormal;
 *         3. the media key session service is in an wrong state.
 *         {@link AV_ERR_NO_MEMORY}, instance has already destroyed or no memory.
 *         {@link AV_ERR_INVALID_VAL}
 *         1. the input codec pointer is non decoder instance or NULL;
 *         2. mediaKeySession is NULL or invalid.
 * @since 11
*/
OH_AVErrCode OH_VideoDecoder_SetDecryptionConfig(OH_AVCodec *codec, MediaKeySession *mediaKeySession,
    bool secureVideoPath);

#ifdef __cplusplus
}
#endif

#endif // NATIVE_AVCODEC_VIDEODECODER_H
/** @} */